Docusaurus MDX 에러

작성일 : 2025.01.09

Docusaurus로 문서 사이트를 만들다 보면 MDX 파일과 관련된 다양한 에러를 만날 수 있습니다.

첫 번째 에러: Import/Export 파싱 실패

문제 상황

다음과 같은 에러 메시지를 만날 수 있습니다:

Error: MDX compilation failed for file "[파일경로].mdx"
Cause: Could not parse import/exports with acorn

이 에러는 MDX 파일의 구조가 올바르지 않을 때 발생합니다. 특히 import 구문의 위치나 마크다운 내용과의 간격이 문제가 될 수 있습니다.

해결 방법

MDX 파일의 구조를 다음과 같이 정리해야 합니다:

---
title: 문서 제목
description: 문서 설명
---

import { Component } from '@site/src/components/Component';

# 제목

내용 시작...

주의할 점:

1. frontmatter(---로 둘러싸인 영역)는 파일의 최상단에 위치해야 합니다
2. import 구문은 frontmatter 다음에 와야 합니다
3. frontmatter와 import 구문 사이, 그리고 import 구문과 마크다운 내용 사이에는 빈 줄이 필요합니다

두 번째 에러: Debug 설정 관련 문제

문제 상황

Docusaurus 3.x 버전에서 다음과 같은 에러가 발생할 수 있습니다:

[ERROR] [ValidationError]: "debug" is not allowed

이는 최신 버전의 Docusaurus에서 설정 구조가 변경되었기 때문입니다.

해결 방법

debug 옵션을 직접 사용하는 대신, 다음과 같은 대체 방법들을 사용할 수 있습니다:

1. 환경 변수를 통한 디버깅

   DEBUG=docusaurus* npm start
   

2. Docusaurus CLI의 verbose 모드 사용

   npm start -- --debug
   

3. 개발 환경에서의 콘솔 로깅

   if (process.env.NODE_ENV === 'development') {
     console.log('디버그 정보:', data);
   }
   

docusaurus.config.js의 docs 설정은 다음과 같이 수정해야 합니다:

docs: {
  sidebarPath: './sidebars.ts',
  editUrl: 'https://github.com/your-username/your-repo/tree/main/',
  
  // MDX 관련 설정
  remarkPlugins: [
    [require('remark-mdx'), { 
      commonmark: true,
      mdExtensions: ['.mdx', '.md']
    }]
  ],
  rehypePlugins: [
    [require('@mapbox/rehype-prism'), { 
      ignoreMissing: true
    }]
  ],
  beforeDefaultRemarkPlugins: [],
  beforeDefaultRehypePlugins: []
}

추가 설정 및 팁

필요한 패키지 설치

MDX 관련 기능을 제대로 사용하기 위해서는 다음 패키지들을 설치해야 합니다:

npm install remark-mdx @mapbox/rehype-prism --save-dev

타입스크립트 사용시 추가 설정

타입스크립트를 사용하는 경우, 다음 타입 정의도 필요할 수 있습니다:

npm install @types/mdx-js__react --save-dev

마무리

Docusaurus의 MDX 관련 에러들은 대부분 파일 구조나 설정의 문제에서 발생합니다. 이러한 에러들은 올바른 파일 구조를 따르고, 최신 버전에 맞는 설정을 사용함으로써 해결할 수 있습니다.

문제 해결 과정에서 가장 중요한 것은 에러 메시지를 주의 깊게 읽고, 프로젝트의 Docusaurus 버전에 맞는 설정을 사용하는 것입니다. 버전별로 설정 방식이 다를 수 있으므로, 공식 문서를 참고하는 것도 도움이 됩니다.

참고 자료

• Docusaurus 공식 문서: MDX 가이드
• MDX 공식 문서: Getting Started